<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    <title>plot3d</title>
  </head>
  <body bgcolor="#FFFFFF">
    <center>Scilab Function</center>
    <div align="right">Last update : 16/11/2005</div>
    <p>
      <b>plot3d</b> - 3D plot of a surface</p>
    <h3>
      <font color="blue">Calling Sequence</font>
    </h3>
    <dl>
      <dd>
        <tt>plot3d(x,y,z,[theta,alpha,leg,flag,ebox])</tt>
      </dd>
      <dd>
        <tt>plot3d(x,y,z,&lt;opt_args&gt;)</tt>
      </dd>
      <dd>
        <tt></tt>
      </dd>
      <dd>
        <tt>plot3d(xf,yf,zf,[theta,alpha,leg,flag,ebox])</tt>
      </dd>
      <dd>
        <tt>plot3d(xf,yf,zf,&lt;opt_args&gt;)</tt>
      </dd>
      <dd>
        <tt></tt>
      </dd>
      <dd>
        <tt>plot3d(xf,yf,list(zf,colors),[theta,alpha,leg,flag,ebox])</tt>
      </dd>
      <dd>
        <tt>plot3d(xf,yf,list(zf,colors),&lt;opt_args&gt;)</tt>
      </dd>
    </dl>
    <h3>
      <font color="blue">Parameters</font>
    </h3>
    <ul>
      <li>
        <tt>
          <b>x,y</b>
        </tt>: row vectors of sizes n1 and n2 (x-axis and y-axis
          coordinates). These coordinates must be monotone.</li>
      <li>
        <tt>
          <b>z</b>
        </tt>: matrix of size (n1,n2). <tt>
          <b>z(i,j)</b>
        </tt> is the value of
          the surface at the point (x(i),y(j)).</li>
      <li>
        <tt>
          <b>xf,yf,zf</b>
        </tt>: matrices of size (nf,n). They define the facets used to draw
          the surface. There are <tt>
          <b>n</b>
        </tt> facets. Each facet
          <tt>
          <b>i</b>
        </tt> is defined by a polygon with <tt>
          <b>nf</b>
        </tt> points.
          The x-axis, y-axis and z-axis coordinates of the points of the ith
          facet are given respectively by <tt>
          <b>xf(:,i)</b>
        </tt>,
          <tt>
          <b>yf(:,i)</b>
        </tt> and <tt>
          <b>zf(:,i)</b>
        </tt>.</li>
      <li>
        <tt>
          <b>colors</b>
        </tt>: a vector of size n giving the color of each facets or a matrix
          of size (nf,n) giving color near each facet boundary (facet color is
          interpolated ).</li>
      <li>
        <tt>
          <b>&lt;opt_args&gt;</b>
        </tt>: This represents a sequence of statements <tt>
          <b>key1=value1,
          key2=value2</b>
        </tt>,... where <tt>
          <b>key1</b>
        </tt>,
          <tt>
          <b>key2,...</b>
        </tt> can be one of the following: theta, alpha
          ,leg,flag,ebox (see definition below).</li>
      <li>
        <tt>
          <b>theta, alpha</b>
        </tt>: real values giving in degree the spherical coordinates of the
          observation point.</li>
      <li>
        <tt>
          <b>leg</b>
        </tt>: string defining the labels for each axis with @ as a field
          separator, for example "X@Y@Z".</li>
      <li>
        <tt>
          <b>flag</b>
        </tt>: a real vector of size three.
          <tt>
          <b>flag=[mode,type,box]</b>
        </tt>.<ul>
          <li>
            <tt>
              <b>mode</b>
            </tt>: an integer (surface color).<ul>
              <li>
                <tt>
                  <b>mode&gt;0</b>
                </tt>: the surface is painted with color
                      <tt>
                  <b>"mode"</b>
                </tt> ; the boundary of the facet is drawn
                      with current line style and color.</li>
              <li>
                <tt>
                  <b>mode=0:</b>
                </tt>a mesh of the surface is drawn.</li>
              <li>
                <tt>
                  <b>mode&lt;0:</b>
                </tt>the surface is painted with color
                      <tt>
                  <b>"-mode"</b>
                </tt> ; the boundary of the facet is not
                      drawn.<p>Note that the surface color treatement can be done
                      using <tt>
                    <b>color_mode</b>
                  </tt> and
                      <tt>
                    <b>color_flag</b>
                  </tt> options through the surface
                      entity properties (see
                      <a href="surface_properties.htm">
                    <tt>
                      <b>surface_properties</b>
                    </tt>
                  </a>).</p>
              </li>
            </ul>
          </li>
          <li>
            <tt>
              <b>type</b>
            </tt>: an integer (scaling).<ul>
              <li>
                <tt>
                  <b>type=0:</b>
                </tt>the plot is made using the current 3D scaling (set
                      by a previous call to <tt>
                  <b>param3d</b>
                </tt>,
                      <tt>
                  <b>plot3d</b>
                </tt>, <tt>
                  <b>contour</b>
                </tt> or
                      <tt>
                  <b>plot3d1</b>
                </tt>).</li>
              <li>
                <tt>
                  <b>type=1:</b>
                </tt>rescales automatically 3d boxes with extreme aspect
                      ratios, the boundaries are specified by the value of the
                      optional argument <tt>
                  <b>ebox</b>
                </tt>.</li>
              <li>
                <tt>
                  <b>type=2:</b>
                </tt>rescales automatically 3d boxes with extreme aspect
                      ratios, the boundaries are computed using the given
                      data.</li>
              <li>
                <tt>
                  <b>type=3:</b>
                </tt>3d isometric with box bounds given by optional
                      <tt>
                  <b>ebox</b>
                </tt>, similarily to
                      <tt>
                  <b>type=1</b>
                </tt>.</li>
              <li>
                <tt>
                  <b>type=4:</b>
                </tt>3d isometric bounds derived from the data, to
                      similarily<tt>
                  <b>type=2</b>
                </tt>.</li>
              <li>
                <tt>
                  <b>type=5:</b>
                </tt>3d expanded isometric bounds with box bounds given
                      by optional <tt>
                  <b>ebox</b>
                </tt>, similarily to
                      <tt>
                  <b>type=1</b>
                </tt>.</li>
              <li>
                <tt>
                  <b>type=6:</b>
                </tt>3d expanded isometric bounds derived from the data,
                      similarily to <tt>
                  <b>type=2</b>
                </tt>.<p>Note that axes boundaries can be customized through
                      the axes entity properties (see
                      <a href="axes_properties.htm">
                    <tt>
                      <b>axes_properties</b>
                    </tt>
                  </a>).</p>
              </li>
            </ul>
          </li>
          <li>
            <tt>
              <b>box</b>
            </tt>: an integer (frame around the plot).<ul>
              <li>
                <tt>
                  <b>box=0:</b>
                </tt>nothing is drawn around the plot.</li>
              <li>
                <tt>
                  <b>box=1:</b>
                </tt>unimplemented (like box=0).</li>
              <li>
                <tt>
                  <b>box=2:</b>
                </tt>only the axes behind the surface are drawn.</li>
              <li>
                <tt>
                  <b>box=3:</b>
                </tt>a box surrounding the surface is drawn and captions
                      are added.</li>
              <li>
                <tt>
                  <b>box=4:</b>
                </tt>a box surrounding the surface is drawn, captions and
                      axes are added.<p>Note that axes aspect can also be customized through
                      the axes entity properties (see
                      <a href="axes_properties.htm">
                    <tt>
                      <b>axes_properties</b>
                    </tt>
                  </a>).</p>
              </li>
            </ul>
          </li>
        </ul>
      </li>
      <li>
        <tt>
          <b>ebox</b>
        </tt>: It specifies the boundaries of the plot as the vector
          <tt>
          <b>[xmin,xmax,ymin,ymax,zmin,zmax]</b>
        </tt>. This argument is used
          together with <tt>
          <b>type</b>
        </tt> in <tt>
          <b>flag</b>
        </tt> : if it is set
          to <tt>
          <b>1</b>
        </tt>, <tt>
          <b>3</b>
        </tt> or <tt>
          <b>5</b>
        </tt> (see above to
          see the corresponding behaviour). If <tt>
          <b>flag</b>
        </tt> is missing,
          <tt>
          <b>ebox</b>
        </tt> is not taken into acoount.<p>Note that, when specified, the <tt>
            <b>ebox</b>
          </tt> argument acts on
          the <tt>
            <b>data_bounds</b>
          </tt> field that can also be reset through
          the axes entity properties (see <a href="axes_properties.htm">
            <tt>
              <b>axes_properties</b>
            </tt>
          </a>).</p>
      </li>
    </ul>
    <h3>
      <font color="blue">Description</font>
    </h3>
    <p>
      <tt>
        <b>plot3d(x,y,z,[theta,alpha,leg,flag,ebox])</b>
      </tt> draws the
    parametric surface <tt>
        <b>z=f(x,y)</b>
      </tt>.</p>
    <p>
      <tt>
        <b>plot3d(xf,yf,zf,[theta,alpha,leg ,flag,ebox])</b>
      </tt> draws a
    surface defined by a set of facets. You can draw multiple plots by
    replacing <tt>
        <b>xf</b>
      </tt>, <tt>
        <b>yf</b>
      </tt> and <tt>
        <b>zf</b>
      </tt> by multiple
    matrices assembled by rows as <tt>
        <b>[xf1 xf2 ...]</b>
      </tt>, <tt>
        <b>[yf1 yf2
    ...]</b>
      </tt> and <tt>
        <b>[zf1 zf2 ...]</b>
      </tt>. Note that data can also be set
    or get through the surface entity properties (see
    <a href="surface_properties.htm">
        <tt>
          <b>surface_properties</b>
        </tt>
      </a>).</p>
    <p></p>
    <p>You can give a specific color for each facet by using
    <tt>
        <b>list(zf,colors)</b>
      </tt> instead of <tt>
        <b>zf</b>
      </tt>, where
    <tt>
        <b>colors</b>
      </tt> is a vector of size <tt>
        <b>n</b>
      </tt>. If
    <tt>
        <b>colors(i)</b>
      </tt> is positive it gives the color of facet
    <tt>
        <b>i</b>
      </tt> and the boundary of the facet is drawn with current line
    style and color. If <tt>
        <b>colors(i)</b>
      </tt> is negative, color id
    <tt>
        <b>-colors(i)</b>
      </tt> is used and the boundary of the facet is not
    drawn.</p>
    <p></p>
    <p>It is also possible to get interpolated color for facets. For that the
    color argument must be a matrix of size nfxn giving the color near each
    boundary of each facets. In this case positive values for colors mean that
    the boundary are not drawn. Note that colors can also be set through the
    surface entity properties (via <tt>
        <b>tlist</b>
      </tt> affectations) and edited
    using <tt>
        <b>color_flag</b>
      </tt> option (see
    <a href="surface_properties.htm">
        <tt>
          <b>surface_properties</b>
        </tt>
      </a>).</p>
    <p></p>
    <p>The optional arguments <tt>
        <b>theta, alpha, leg ,flag, ebox</b>
      </tt>, can
    be passed by a sequence of statements <tt>
        <b>key1=value1,
    key2=value2</b>
      </tt>, ... In this case, the order has no special meaning.
    Note that all these optional arguments except <tt>
        <b>flag</b>
      </tt> can be
    customized through the axes entity properties (see
    <a href="axes_properties.htm">
        <tt>
          <b>axes_properties</b>
        </tt>
      </a>). As described before, the <tt>
        <b>flag</b>
      </tt>
    option deals with surface entity properties for <tt>
        <b>mode</b>
      </tt> (see
    <a href="surface_properties.htm">
        <tt>
          <b>surface_properties</b>
        </tt>
      </a>) and axes properties for <tt>
        <b>type</b>
      </tt>
    and <tt>
        <b>box</b>
      </tt> (see <a href="axes_properties.htm">
        <tt>
          <b>axes_properties</b>
        </tt>
      </a>).</p>
    <p></p>
    <p>You can use the function <tt>
        <b>genfac3d</b>
      </tt> to compute four sided
    facets from the surface <tt>
        <b>z=f(x,y)</b>
      </tt>. <tt>
        <b>eval3dp</b>
      </tt> can
    also be used.</p>
    <p></p>
    <p>Enter the command <tt>
        <b>plot3d()</b>
      </tt> to see a demo.</p>
    <h3>
      <font color="blue">More information</font>
    </h3>
    <dl>
      <p>To get more information on the plot3d old syntax , use the
    <a href="plot3d_old_version.htm">
          <tt>
            <b>plot3d_old_version</b>
          </tt>
        </a> help document.</p>
    </dl>
    <h3>
      <font color="blue">Examples</font>
    </h3>
    <pre>
// simple plot using z=f(x,y) 
t=[0:0.3:2*%pi]';
z=sin(t)*cos(t');
plot3d(t,t,z) 
// same plot using facets computed by genfac3d
[xx,yy,zz]=genfac3d(t,t,z); 
clf() 
plot3d(xx,yy,zz)
// multiple plots 
clf()
plot3d([xx xx],[yy yy],[zz 4+zz]) 
// multiple plots using colors 
clf()
plot3d([xx xx],[yy yy],list([zz zz+4],[4*ones(1,400) 5*ones(1,400)])) 
// simple plot with viewpoint and captions 
clf() 
plot3d(1:10,1:20,10*rand(10,20),alpha=35,theta=45,flag=[2,2,3]) 
// plot of a sphere using facets computed by eval3dp 
deff("[x,y,z]=sph(alp,tet)",["x=r*cos(alp).*cos(tet)+orig(1)*ones(tet)";.. 
 "y=r*cos(alp).*sin(tet)+orig(2)*ones(tet)";.. 
 "z=r*sin(alp)+orig(3)*ones(tet)"]); 
r=1; orig=[0 0 0]; 
[xx,yy,zz]=eval3dp(sph,linspace(-%pi/2,%pi/2,40),linspace(0,%pi*2,20)); 
clf();plot3d(xx,yy,zz) 
clf();
f=gcf();
f.color_map = hotcolormap(128); 
r=0.3;orig=[1.5 0 0]; 
[xx1,yy1,zz1]=eval3dp(sph,linspace(-%pi/2,%pi/2,40),linspace(0,%pi*2,20)); 
cc=(xx+zz+2)*32;cc1=(xx1-orig(1)+zz1/r+2)*32; 
clf();plot3d1([xx xx1],[yy yy1],list([zz,zz1],[cc cc1]),theta=70,alpha=80,flag=[5,6,3])

//Available operations using only New Graphics...
delete(gcf());
t=[0:0.3:2*%pi]'; z=sin(t)*cos(t');
[xx,yy,zz]=genfac3d(t,t,z);
plot3d([xx xx],[yy yy],list([zz zz+4],[4*ones(1,400) 5*ones(1,400)]))
e=gce();
f=e.data;
TL = tlist(["3d" "x" "y" "z" "color"],f.x,f.y,f.z,6*rand(f.z)); // random color matrix
e.data = TL;
TL2 = tlist(["3d" "x" "y" "z" "color"],f.x,f.y,f.z,4*rand(1,800)); // random color vector
e.data = TL2;
TL3 = tlist(["3d" "x" "y" "z" "color"],f.x,f.y,f.z,[20*ones(1,400) 6*ones(1,400)]);
e.data = TL3;
TL4 = tlist(["3d" "x" "y" "z"],f.x,f.y,f.z); // no color
e.data = TL4;
e.color_flag=1 // color index proportional to altitude (z coord.)
e.color_flag=2; // back to default mode
e.color_flag= 3; // interpolated shading mode (based on blue default color)
clf()
plot3d([xx xx],[yy yy],list([zz zz+4],[4*ones(1,400) 5*ones(1,400)]))
h=gce(); //get handle on current entity (here the surface)
a=gca(); //get current axes
a.rotation_angles=[40,70];
a.grid=[1 1 1]; //make grids
a.data_bounds=[-6,0,-1;6,6,5];
a.axes_visible="off"; //axes are hidden
a.axes_bounds=[.2 0 1 1];
h.color_flag=1; //color according to z
h.color_mode=-2;  //remove the facets boundary by setting color_mode to white color
h.color_flag=2; //color according to given colors
h.color_mode = -1; // put the facets boundary back by setting color_mode to black color
f=gcf();//get the handle of the parent figure    
f.color_map=hotcolormap(512);
c=[1:400,1:400];
TL.color = [c;c+1;c+2;c+3];
h.data = TL;
h.color_flag=3; // interpolated shading mode

</pre>
    <h3>
      <font color="blue">See Also</font>
    </h3>
    <p>
      <a href="eval3dp.htm">
        <tt>
          <b>eval3dp</b>
        </tt>
      </a>,&nbsp;&nbsp;<a href="genfac3d.htm">
        <tt>
          <b>genfac3d</b>
        </tt>
      </a>,&nbsp;&nbsp;<a href="geom3d.htm">
        <tt>
          <b>geom3d</b>
        </tt>
      </a>,&nbsp;&nbsp;<a href="param3d.htm">
        <tt>
          <b>param3d</b>
        </tt>
      </a>,&nbsp;&nbsp;<a href="plot3d1.htm">
        <tt>
          <b>plot3d1</b>
        </tt>
      </a>,&nbsp;&nbsp;<a href="clf.htm">
        <tt>
          <b>clf</b>
        </tt>
      </a>,&nbsp;&nbsp;<a href="gca.htm">
        <tt>
          <b>gca</b>
        </tt>
      </a>,&nbsp;&nbsp;<a href="gcf.htm">
        <tt>
          <b>gcf</b>
        </tt>
      </a>,&nbsp;&nbsp;<a href="xdel.htm">
        <tt>
          <b>xdel</b>
        </tt>
      </a>,&nbsp;&nbsp;<a href="delete.htm">
        <tt>
          <b>delete</b>
        </tt>
      </a>,&nbsp;&nbsp;</p>
    <h3>
      <font color="blue">Author</font>
    </h3>
    <p>J.Ph.C.</p>
  </body>
</html>
